Understanding GitHub App Rate Limits

GitHub Apps interact with the GitHub API to automate tasks, integrate services, and extend GitHub's functionality. Like other API consumers, GitHub Apps are subject to rate limits to ensure fair usage, prevent abuse, and maintain the stability and performance of the platform. These limits control the number of API requests an app can make within a specific timeframe.

Unlike user-based rate limits (which apply per authenticated user) or OAuth App rate limits, GitHub App rate limits are primarily associated with an installation of the app on a repository or organization.

How GitHub App Rate Limits Work

GitHub Apps have a rate limit based on the number of installations and the types of API requests made.

• Core Limit: The most common limit is a per-installation limit. Each installation of a GitHub App gets its own quota of API requests. This means an app installed on 10 organizations or repositories has 10 independent rate limits, one for each installation.
• Concurrent Requests: There can also be limits on the number of concurrent requests allowed for a single installation.
• Specific Endpoints: Certain API endpoints might have stricter or different rate limits than the general core limit.

The exact numerical limits can change over time and are detailed in GitHub's official API documentation. It's essential to consult the latest documentation for the most current figures.

Why Rate Limits Matter for GitHub Apps

Hitting rate limits can cause significant issues for a GitHub App:

• API Request Failures: Subsequent API requests will fail with a 403 Forbidden status code and a specific error indicating the rate limit has been exceeded.
• Reduced Functionality: The app may stop working correctly until the rate limit resets, disrupting automated workflows or integrations.
• Poor User Experience: Users relying on the app's functionality will experience delays or failures.
• App Suspension: Repeated or severe rate limit violations could potentially lead to action against the app.

Understanding and respecting rate limits is crucial for building reliable and scalable GitHub Apps.

Checking Rate Limit Status

GitHub communicates the current rate limit status for an installation through HTTP response headers for every API request. Monitoring these headers allows an app to track its consumption and react before hitting the limit.

The key response headers are:

• X-RateLimit-Limit: The maximum number of requests allowed within the current rate limit window for this installation.
• X-RateLimit-Remaining: The number of requests remaining in the current window.
• X-RateLimit-Reset: The timestamp (in UTC epoch seconds) when the current rate limit window resets and the remaining count is replenished.

By inspecting these headers after each API call, an app can know how close it is to hitting the limit and how long it needs to wait if the limit is reached.

Strategies for Managing GitHub App Rate Limits

Several techniques can help GitHub Apps stay within their allocated rate limits:

• Monitor X-RateLimit-Remaining: Regularly check the X-RateLimit-Remaining header. If the number is low, the app can slow down its requests or pause processing for that installation until the reset time indicated by X-RateLimit-Reset.
• Implement Exponential Backoff: When a rate limit error (403 Forbidden with a specific rate limit message) occurs, the app should not immediately retry the request. Instead, it should wait for a period, then retry. If it fails again, it should wait for a longer period. This pattern of progressively longer waits is called exponential backoff. The X-RateLimit-Reset header provides the exact time to wait until the next request can likely succeed.
• Cache API Responses: Store data retrieved from the GitHub API locally where possible, rather than fetching it repeatedly. This reduces the number of API calls needed. Ensure the cache has an appropriate expiration time or is invalidated by relevant GitHub events (webhooks).
• Use Conditional Requests: For resources that might not change frequently, use the If-None-Match header with the ETag value from a previous response or the If-Modified-Since header with the Last-Modified date. If the resource hasn't changed, the API will return a 304 Not Modified status, which does not count against the rate limit.
• Reduce Request Volume:
  • Fetch only the data needed using query parameters or specific API endpoints.
  • Avoid polling the API for changes; instead, rely on GitHub Webhooks to receive real-time notifications about events (like pushes, pull requests, issues) and trigger app logic based on those events. This is significantly more efficient than constantly querying the API.
  • Combine related operations where possible, if the API supports it (though batching is not a general feature across the GitHub API).
• Optimize Event Handling: If the app processes webhook events, ensure that processing is efficient and that it doesn't trigger unnecessary API calls. For instance, if an app only cares about pull request events, configure the webhook to only send those events.

Handling Rate Limit Errors

When an API request fails due to hitting the rate limit, the response will include a 403 Forbidden status code and specific information in the response body or headers indicating the rate limit was exceeded.

A robust GitHub App should:

1. Detect the 403 status code.
2. Check if the error is specifically a rate limit error (examine the response body or headers).
3. If it's a rate limit error, inspect the X-RateLimit-Reset header.
4. Pause further API calls for that installation until the time indicated by X-RateLimit-Reset.
5. Implement a retry mechanism, ideally with exponential backoff, respecting the reset time.

Proper error handling for rate limits ensures the app recovers gracefully and doesn't make continuous, failing requests that could exacerbate the problem or lead to further issues.